Analysis templates suggested updates by iRaindrop · Pull Request #357 · cncf/techdocs

iRaindrop · 2026-06-09T05:32:24Z

This PR is for collaborating on changes to the CNCF Techdocs analysis template(s).

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

netlify · 2026-06-09T05:32:29Z

✅ Deploy Preview for cncf-techdocs ready!

Name	Link
🔨 Latest commit	`3dcf00a`
🔍 Latest deploy log	https://app.netlify.com/projects/cncf-techdocs/deploys/6a2a0db6513de70008fcd516
😎 Deploy Preview	https://deploy-preview-357--cncf-techdocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

iRaindrop · 2026-06-11T16:08:41Z

  users needing more help? (FAQ, Troubleshooting)
 - If the product exposes an API, is there a complete reference?
 - Is content up to date and accurate?



Consider adding for information architecture:

Are prerequisites consistent in quickstarts and install topics? Consider consolidating if applicable.

Are there instructions on how to install something that is better served by linking to official documentation?

Is there content in other places that would be helpful for getting started content.

Keep in mind that these criteria are meant to embody best practices for the most important aspects of the documentation. If you're using words like "Consider ...", "better served", and "helpful", you might be describing nice-to-haves. The goal with these criteria is to

Bullet #1 brings up a whole can of worms around document reuse. Prerequisites to procedures vary in length. At one end of the spectrum, if something is boilerplate-y enough that it can be referred to from several procedures, to my mind it's more of a sub-procedure that can be referred to in a single step. At the other end of the spectrum, short prereqs might be worth including in-line even if they're duplicated because you don't want to send users pinballing around the doc to get one task done. You can also write something once and #include it where applicable, but not all site generators support this. The upshot is that IMO this is a judgement that the maintainers have to make on a per-project basis.

Bullet #2 is a good point. I've seen a lot of OSS pages that are duplicates of how to do something with a component tool (especially Kubernetes configuration) that could have been replaced with a short explanation and a link to the component's documentation. On the other hand, too much documentation is better than no documentation. I'd say something like "If your product builds on or incorporates another product (such as Kubernetes), does it provide external references where needed to install and configure those products?"

Not sure what you're getting at in Bullet #3. Please explain further.

iRaindrop · 2026-06-11T16:09:54Z


+Replace link placeholders in brackets, such as [_PROJECT_][project-website],
+with the actual link surrounded by parenthesis.
+


I added this. Remove if you think its not needed.

iRaindrop · 2026-06-11T16:12:35Z

  [Inclusive Naming Initiative](https://inclusivenaming.org) website?
 - Does the project use language like "simple", "easy", etc.?

+### AI Optimization and Discoverability


New section. Please opine.

UPDATE: Nate and I discussed this and agreed it would be better in a separate topic. @nate-double-u - how about naming it ai-guidance.md?

The currently popular description seems to be "AI friendly." I like "optimization and discovery" better -- it's more precise -- but I'd put "AI friendly" in the description somewhere for searchability.

What's the rationale for having a separate document?

iRaindrop · 2026-06-11T16:15:47Z


 #### Project governance documentation

 ## Website and infrastructure


We can consider removing Website and infrastructure as writers only have minimal info or context to complete, and Nate has ok'd not including it.

I think this is situational. In some cases the website and infrastructure review is warranted, in other cases I'm OK dropping it.

I agree with Nate. There are going to be AI-related components as well, such as an AGENTS.md file.

dwelsch-esi

Since we're taking this opportunity to review and improve the analysis criteria, a couple of overall comments:

The analysis process evaluates against the maturity level (or the proposed maturity level) of the project. We don't explicitly map criteria requirements to maturity level, except briefly for website guidelines. Should we consider revising the criteria document to explictly map leveled criteria to the incubating and graduated levels?
The doc criteria don't include any process requirements. I understand that each project has its own processes, procedures, and culture. (Some process is alluded to, for example with requirements like "Who reviews and approves documentation pull requests?") On the other hand, process is really what a maturity model is about. Should we start thinking about including doc process in the criteria, especially for a graduated project? These would necessarily have to be general principles, adaptable to a range of OSS projects and their methodologies. For example, we ask if the documentation has versions and release notes, but not if the project has a versioning process.

A maintenance question for the CNCF TechDocs analysis docments: We duplicate the criteria in the analysis template. This makes the template easy to use but risks getting the template out of sync with the criteria. Is there a better way to do this?

dwelsch-esi · 2026-06-12T21:01:56Z

  stored; this might be its own repo or a directory in the project main repo

+Replace link placeholders in brackets, such as [_PROJECT_][project-website],
+with the actual link surrounded by parenthesis.


Suggested change

with the actual link surrounded by parenthesis.

with a Markdown-style link.

dwelsch-esi · 2026-06-12T21:36:51Z

  users needing more help? (FAQ, Troubleshooting)
 - If the product exposes an API, is there a complete reference?
 - Is content up to date and accurate?



Keep in mind that these criteria are meant to embody best practices for the most important aspects of the documentation. If you're using words like "Consider ...", "better served", and "helpful", you might be describing nice-to-haves. The goal with these criteria is to

Bullet #1 brings up a whole can of worms around document reuse. Prerequisites to procedures vary in length. At one end of the spectrum, if something is boilerplate-y enough that it can be referred to from several procedures, to my mind it's more of a sub-procedure that can be referred to in a single step. At the other end of the spectrum, short prereqs might be worth including in-line even if they're duplicated because you don't want to send users pinballing around the doc to get one task done. You can also write something once and #include it where applicable, but not all site generators support this. The upshot is that IMO this is a judgement that the maintainers have to make on a per-project basis.

Bullet #2 is a good point. I've seen a lot of OSS pages that are duplicates of how to do something with a component tool (especially Kubernetes configuration) that could have been replaced with a short explanation and a link to the component's documentation. On the other hand, too much documentation is better than no documentation. I'd say something like "If your product builds on or incorporates another product (such as Kubernetes), does it provide external references where needed to install and configure those products?"

Not sure what you're getting at in Bullet #3. Please explain further.

dwelsch-esi · 2026-06-12T21:39:34Z


 #### Project governance documentation

 ## Website and infrastructure


I agree with Nate. There are going to be AI-related components as well, such as an AGENTS.md file.

dwelsch-esi · 2026-06-12T21:49:30Z

  [Inclusive Naming Initiative](https://inclusivenaming.org) website?
 - Does the project use language like "simple", "easy", etc.?

+### AI Optimization and Discoverability


The currently popular description seems to be "AI friendly." I like "optimization and discovery" better -- it's more precise -- but I'd put "AI friendly" in the description somewhere for searchability.

What's the rationale for having a separate document?

dwelsch-esi · 2026-06-12T21:54:33Z

  contributors to the _PROJECT_ OSS project
 - **Website:** concerns the mechanics of publishing the documentation, and
  includes branding, website structure, and maintainability



Suggested change

A fourth area of concern, AI optimization and discovery, might be included in this analysis. If so, it is discussed in a separate document, `ai-guidance.md`.

dwelsch-esi · 2026-06-13T00:17:14Z

 - Might a [mobile-first][] design make sense for your project?
 - Are color contrasts significant enough for color-impaired readers?
 - Are most website features usable using a keyboard only?
 - Does text-to-speech offer listeners a good experience?


Suggested change

Dupe.

dwelsch-esi · 2026-06-13T00:18:24Z

 We evaluate on the following:

 - Are color contrasts significant enough for color-impaired readers?
 - Are most website features usable using a keyboard only?


Suggested change

- Are all vital website features usable using a keyboard only?

dwelsch-esi · 2026-06-13T00:18:42Z


 - Are color contrasts significant enough for color-impaired readers?
 - Are most website features usable using a keyboard only?
 - Does text-to-speech offer listeners a good experience?


Suggested change

- Does text-to-speech offer listeners a usable experience?

dwelsch-esi · 2026-06-13T00:20:04Z


 [accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility

 ### Branding


This isn't my area, but are all the branding criteria still relevant and important? Are there others that should be added?

dwelsch-esi · 2026-06-13T00:20:54Z


 We evaluate on the following:

 - Analytics:


Are there any AI-era SEO or findability criteria we should add?

minor edit to add doc for commenting

11531af

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

iRaindrop requested a review from dwelsch-esi June 9, 2026 05:32

Merge branch 'main' into analysis-templates-updates

0180b2b

iRaindrop marked this pull request as draft June 9, 2026 05:39

iRaindrop added 11 commits June 10, 2026 13:30

added AI section

30e402c

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

spelling fix

2edb12a

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

removed unneeded example link

bc2b86d

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

spelling - fomratting fixes

be4fbff

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

put llms in code to fix spelling

c754d47

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

trying quotes

dc567e2

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

changed llms.txt to _AGENT_ placedholder

ae6acf8

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

spelling fix

32219eb

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

added back llms.txt

3253ec1

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

ran prittier

0d1e328

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

added llms to word list

3dcf00a

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

iRaindrop commented Jun 11, 2026

View reviewed changes

dwelsch-esi reviewed Jun 13, 2026

View reviewed changes


		Replace link placeholders in brackets, such as [_PROJECT_][project-website],
		with the actual link surrounded by parenthesis.


		#### Project governance documentation

		## Website and infrastructure

	with the actual link surrounded by parenthesis.
	with a Markdown-style link.



	A fourth area of concern, AI optimization and discovery, might be included in this analysis. If so, it is discussed in a separate document, `ai-guidance.md`.


	- Are all vital website features usable using a keyboard only?


		[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility

		### Branding

Conversation

iRaindrop commented Jun 9, 2026

Uh oh!

netlify Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cncf-techdocs ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iRaindrop Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dwelsch-esi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify Bot commented Jun 9, 2026 •

edited

Loading

iRaindrop Jun 11, 2026 •

edited

Loading